                 ==================================
                 |                                |
                 |   MSDOS File Utilities v2.40a  |
                 |                                |
                 ==================================

             Copyright 1993-1999 by Peter Watson
             ===================================

These files contain the latest versions of my MSDOS utility programs, including utilities to *WRITE* to MSDOS disks.

                     vvvvvvvvv
**** Please read the Rev.Notes and Credits files as well. ****
                     ^^^^^^^^^

Notice:  These files are SHAREWARE. This means you may copy them, and you
======   are encouraged to give copies to your friends, or upload them to
         online services. However, you must ensure that all files are
         included when making copies for others, and you may not modify
         any of the files.

         You may use the utility programs on this disk for a period of
         two weeks. At the end of that time you are required to send the
         SHAREWARE fee to the address below, or to erase any copies of the
         files that you may have. When I receive your SHAREWARE fee, you
         will be registered as a legitimate user. This will entitle you to
         support, I will send you the latest version of the MSDOS Utilities
         (if you do not have the latest version), and any suggestions you
         may have are much more likely to be acted on.

         Registered users are entitled to use any future (non-commercial)
         upgrades for free. To request an upgrade directly, send $5 to the
         address below. When registering, please mention the version number
         of the MSDOS Utilities as shown by the file named 'Disk.Ver.x.xx'.

         Payments in overseas currencies made by personal cheques are mostly
         eaten up by Australian bank charges. Bank drafts drawn in Australian
         dollars on an Australian bank are good. Australian or US cash is best.
         If you send a check, an extra $5 to cover costs is required.

         ==================================================================
         = BlueDisk Owners =
         ===================
         If you received the MSDOS Utilities as part of the software
         included with the BlueDisk interface created by Joachim Lange
         of ///SHH Systeme, then you do *not* need to pay the shareware
         fee mentioned above. This is because ///SHH Systeme has licensed
         the MSDOS Utilities for distribution with the BlueDisk interface.

         Updates to the MSDOS Utilities should still be obtained directly
         from Peter Watson as described above (or they may be available
         from some online services).
         ==================================================================

         Address for shareware fees, upgrade fees and general correspondence:

                    Peter Watson
                    13 Ilios Close
                    Forest Hill  Vic  3131
                    Australia

         Comments by email are welcome. My InterNet address is :
                    paw@acslink.net.au
                    paw77@hotmail.com

         If you include your email address (InterNet, Genie, CompuServe, AOL)
         when registering, I can respond much more easily!

         Read the Credits file to see the benefits of paying for shareware!

==================================================================
          The SHAREWARE fee for this disk is :-
                     US$15.00
                    AUS$20.00
==================================================================
All files in this package are Copyright 1993-1999 by Peter Watson,
except for parts that are Copyright 1987-1994 by ByteWorks (see below).
==================================================================

Introduction
============
The MSDOS Utilities form a set of command shell utilities that allow files and directories on MSDOS disks to be read, *WRITTEN*, listed, deleted, renamed, etc. Other utilities allow disks to be copied, formatted and (re)labeled. Any size disk should be supported (except for formatting), including partitioned hard disks and Applied Engineering PC Transporter MSDOS partition files.

Note: In 1997 a GUI (graphical user interface) version of the MSDOS Utilities was released. This is the MUG! (MSDOS Utilities Graphical !nterface) NDA. This single program performs similar functions to the MSDOS Utilties, but allows files to be chosen from scrolling lists, and has the advantage of being available from within any GUI application. Registered users of the MSDOS Utilities are entitled to an upgrade for half price.

What are the benefits of the MSDOS Utilities over Apple's MSDOS FST? For reading from MSDOS disks, not a lot - except that the MSDOS FST can't handle disks containing long file names created by Windows, or partitioned disks (eg. Zip or SyQuest cartridges) or Applied Engineering PC Transporter (AEPCT) MSDOS partition files, and it does not do any text file conversion when copying files. (Well, maybe there *are* a few gaps!)

On the other hand, Apple does not support writing to MSDOS disks in any way (eg. copying files to MSDOS disks, formatting disks, renaming files, etc) - all items supported by these utilities. Also, the MSDOS FST requires GS/OS System 6.01, (and uses more memory and disk space at boot time), while the MSDOS Utilities will work with System 6.0. At present the utilities require System 6 as this is a requirement of programs compiled with ORCA/C 2.0.

For details on using each program, (after reading this file!), look at the help files in the HELP directory. The help file named MSDOS gives an overview of the various utility files, and the help file named MSDOS.PARMS gives an overview of the command syntax. The programs have been written to run under any IIgs command shell, but have only been tested under the ORCA/M shell v.2.0x, GNO/ME (preferably v2.xx), ProSel-16 and the included mini-command shell, COMMAND.COM.

I am reasonably confident about the programs, but until they have been tested on a wider range of disks and files I am not willing to swear that they are bombproof. To put it more bluntly, all the programs are used at your own risk. If you are not prepared to take the risk, don't use the programs. Having said that, I use them and my hard disk is still in one piece! And Norton's Utilities doesn't complain about MSDOS disks created by these utilities!

Note: A very simple command shell (COMMAND.COM) is now included with the
====  utilities. This is to assist people who do not have their own command
      shell program. It has been specifically designed for the MSDOS Utilities,
      but has been successfully tested with a number of other commands from
      other sources. It will also run normal GS/OS and ProDOS 8 applications,
      including ApplSoft BASIC programs. Type 'HELP' and 'HELP COMMAND.COM' at
      the prompt for more information.

Hardware Requirements
=====================
The programs were developed on a system using an Apple II 3.5 Disk Controller with an Apple 3.5" FDHD 'SuperDrive'. They have also been tested with an Applied Engineering High Density drive attached to Apple's controller card, with 5.25" and 3.5" TransDrives attached to an Applied Engineering PC Transporter (AEPCT), with MSDOS drives attached to a BlueDisk interface, and with 100Mb Zip and 44Mb and 105Mb syQuest drives formatted for MSDOS (attached to Apple High Speed SCSI controller or RamFast interface cards). Many people are successfully using Floptical drives, usually using RamFast SCSI controller cards. The only limitation is that formatting disks larger than a 21Mb Floptical is not supported.

Any MSDOS SCSI disk drive *should* be supported. In fact, so should *ANY* disk drive that is capable of reading a block from a disk formatted for MSDOS. If you are unsure, try using a disk zap utility to read block 0. If you do not get an I/O error, then the utilities should work with it!.

One known exception seems to be the FDC-10 card, which uses custom drivers that work in ProDOS 8, but not under GS/OS. I don't have access to one of these cards to allow me to check it out.

The utilities will also work with PC Transporter MSDOS partition files (acting as an MSDOS hard disk) on a GS/OS hard disk.

The utilities will *not* be able to access MSDOS disks if you only have an Apple or compatible 800K drive. Even with a PC Transporter card this is still true, although an 800K drive attached to a PCT can read and write MSDOS disks while running MSDOS on the PCT. This is a limitation of the Applied Engineering drivers provided for GS/OS. (The only exception to this rule is with 800K MSDOS disks created using the PC Transporter, which are not very common!)

Using Apple's FDHD SuperDrive and controller card, a 1440K High-Density disk formatted as 720K on a MSDOS machine will not be recognised as a formatted disk. This is a restriction of the drive and/or controller card (it also applies with these types of disks in a Macintosh). A similar restriction *may* apply to other drive and/or controller card combinations.

Software Requirements
=====================
The only software requirement is GS/OS System 6.0 or later. The MSDOS Utilities require a command shell such as ORCA/M or ProSel-16, however a simple shell is included with the utilities.

If you use ProSel-16 or GNO/ME v1.x (v2.x works properly), the screen is usually cleared after each command. This is a "feature" of the console interface of these shells - sorry! ORCA/M v1.x also sometimes gets the screen confused, particularly on the first command. For both ORCA/M and GNO/ME, I *strongly* recommend upgrading to the latest releases as they are far superior and well worth the price of the upgrade.

Although not required, the MSDOS FST may still be useful. When combined with the MSDOS Utilities it allows you to copy files between two MSDOS disks (or between two directories on the same disk) without having to copy to a GS/OS disk first. However, that the MSDOS FST has trouble with hard disks and disks containing long file names, which can limit the usefulness of this option.

Installation
============
A list of the included files is given near the end of this document. Note that with the exception of the help files for COMMAND.COM, all the files/programs are independent, so if you are short on disk space you only need to copy those programs you need. In any case, you should make a backup copy of the entire MSDOS Utilities disk just for emergencies. And you should definitely do this before using MPatch (see MPatch Utility below) to change any defaults.

Since the size of the MSDOS Utilities programs and support files has grown to be larger than a single 800K disk, some of the less commonly used utilities have been compressed using ShrinkIt GS to save space. To extract these utilities onto another disk, simply execute the file Extras.SEA. You will be prompted for a location for the extracted files (make sure you choose a different disk!), then the files will be automatically extracted.

The following sections provide installation suggestions for various command shell environments. I *very strongly* suggest you read the section "Setting a Default Device Number" later in this file - the utilities are MUCH simpler to use with a default device!

--------------------
ORCA Shell
--------------------
The programs may be executed from a diskette, or stored in a folder on a hard disk. With the exception of COMMAND.COM (see below), none of the programs have any particular location requirements. However, under the ORCA/M shell, they are easiest to use if they are stored in the */UTILITIES directory (ie. the prefix 6 or 17 directory), with entries in the SYSCMND table for each command. A sample set of SYSCMND entries has been provided. The help files should be copied to the */UTILITIES/HELP directory.

If you are using a version of the ORCA/M shell before v2.00 (ORCA/M v1.x or APW), you will have difficulty using default device numbers or AEPCT MSDOS partition files. This is because the MSDOS Utilities expect prefix 9 to point to the directory containing the commands. You will need to set prefix 9 yourself using a third party utility since the early versions of the ORCA/M shell do not understand about GS/OS prefixes 8 to 31.

Another side effect if using an early version of the ORCA/M shell is that the screen displays can get "confused", particularly on the first command. One way to help avoid this is to press the return key until the cursor is at the bottom of the screen before isuing any commands. As mentioned earlier, this is a limitation of the console driver used by ORCA/C.

For most purposes, the APW command shell is identical to version 1.0 of the ORCA/M shell. Under APW however the MSDOS commands quit from the shell when finished which may limit their usefulness somewhat! This does not happen with v1.1 and later of the ORCA/M shell (I do not have v1.0 to test). In any case, I *strongly* recommend that anyone still using APW or ORCA/M v1.x should upgrade to v2.0!

Hint!

For those people who liked having a separate MRD (Remove Directory) program (as used to be available in the MSDOS Utilities version until it was merged with MDel), a reasonable facsimile can be created by creating an alias in your 'login' file, as follows:   alias MRD MDel -d
Unfortunately, this only works properly when using default device numbers!

--------------------
GNO/ME
--------------------
Sorry - I have easy access to GNO/ME, so I can't describe the installation process. However, there are many people using the MSDOS Utilities under the GNO/ME command shell with no problems. However, you *do* need to have version 2.0 or later to avoid some strange screen display problems.

If my understanding of the GNO/ME environment is correct, then the utilities are probably placed in the /bin directory, or in a directory which has been added to the $PATH variable. The help files are not designed for use with the 'man' utility, so I am not sure where they should be located. The default device number (described below) can be specified as a shell variable as well as being placed in a special file.

GNO/ME users should also see the MDEL 'hint' in the ORCA Shell section above.

--------------------
ProSel-16
--------------------
To use ProSel-16 as your command shell, the program files should be copied to the prefix 6 folder, normally named COMMANDS in the ProSel.16 folder. The help files should be copied to the HELP.FILES folder in the ProSel.16 folder. To simply use the MSDOS Utilities temporarily (without copying them to the ProSel disk), issue the ProSel shell command 'PREFIX 6=/MSDOS.Tools'. See the ProSel documentation for further information on using the ProSel command shell.

A further requirement for using default device numbers or PC Transporter MSDOS partition files is to enter the command 'PREFIX 9=6' (setting prefix 9 to the same place as prefix 6). This assumes that the 'MSDOS.Device' and/or 'AEPCT.HD.Name' files have been placed in the same directory as the MSDOS Utility commands. You can also permanently set the default value for prefix 9 using ProSel's Modify Parameters option.

See the notes below for further information on these files, and the explanation in the ORCA/M section above as to why this step is required.

--------------------
COMMAND.COM
--------------------
A special requirement for using COMMAND.COM as your command shell is that the 'help' files must be stored in a folder named 'HELP' in the same directory as the COMMAND.COM file. If this is not done, then the 'HELP' command will not be able to automatically find the various help files (althought the 'TYPE' command could be used to list them manually instead). Remember, COMMAND.COM is only required if you have no other command shell to execute the MSDOS Utilities.

Note: If you wish to run Applesoft BASIC programs from COMMAND.COM, you must ensure that BASIC.SYSTEM (if you are running System 6) or BASIC.LAUNCHER is in the root (main) disk folder or in the SYSTEM folder of the 'startup' disk.

Note: If you have a PC Transporter MSDOS partition file on your hard disk, see the notes below.

Note: To set a default MSDOS device number, see the notes in the next section.

--------------------
MPatch Utility
--------------------
Before using MPatch, I recommend making a copy of the program(s) to be patched. This means you are protected if there is any problem during the patching process which corrupts the file (unlikely, but always a possibility with *any* program).

The MPatch utility may be used to change the defaults of some utility options. For example, the '/B' switch is used by MCopy and GMCopy to specify that the file should always be copied in 'binary' mode, ie. without adding/stripping linefeed characters as required for normal text files. These options can be made the default by executing the commands :

     MPATCH MDir      /C      Make Creation date mode the default
     MPATCH MDir      /F      Make Fast (no Freespace) display the default

     MPATCH MType     /Q      Make Quiet mode the default
     MPATCH MType     /X      Make hex dump mode the default

     MPATCH MCopy     /A      Disable auto text file recognition by default
     MPATCH MCopy     /B      Make Binary mode the default
     MPATCH MCopy     /O      Make file Overwrite mode the default
     MPATCH MCopy     /P      Make Prompt mode the default

     MPATCH GMCopy    /A      Disable auto text file recognition by default
     MPATCH GMCopy    /B      Make Binary mode the default
     MPATCH GMCopy    /O      Make file Overwrite mode the default

     MPATCH MRename   /L      Force the creation of Windows 95 long file names

     MPATCH MDel      /D      Default to Directory delete mode
     MPATCH MDel      /P      Always prompt before deleting

     MPATCH MFormat   /Q      Make Quick-format mode the default
     MPATCH MFormat   /X      Default to auto-eject disabled mode
     MPATCH MFormat   /P      Use GS/OS format dialogue by default

     MPATCH MDiskCopy /X      Default to auto-eject disabled mode
     MPATCH MDiskCopy /F      Default to always pre-formatting target disks

The following patch may be applied to all commands supporting PCT volume files, and is unique because it does not correspond to a 'normal' parameter for the commands :

     MPATCH xxxxxxxx  /0      Suppress the PCT volume name(s) message by default
                       
The effect of patches may be permanently reversed by executing the commands again, and temporarily reversed by specifying the option switch on the command (with the exception of '/0'). For example, if MCopy has been patched to make '/B' the default, then specifying '/B' on the MCopy command will turn OFF binary mode for that copy!

At present, these are the only patch options, although others may be added by the time you read this. Since it does no harm to try, if you dislike the default value for an option in a utility, try the patch program. If it fails to find the patch location, let me know and I will probably modify the utility concerned to be patchable.

Hint!

For those people who liked having a separate MRD (Remove Directory) program, a reasonable facsimile can be created by making a copy of MDel, renaming it to MRD, then using MPatch to make the '/D' option the default!


==============================
Assumptions, Caveats and Notes
==============================

--------------------
Supported Command Shells
--------------------
The MSDOS Utilities are designed to work from a command shell, such as ORCA/M or GNO/ME. They should work from any other program shell that supports command lines such as ProSel-16 (tested), Davex and ECP-16 (untested), etc. [I have had a report that ECP-16 does not work, but there is no programming reason why this should be so. It *may* be due to the way ORCA/C v2 attempts to use the GS/OS console driver, which may not work with ECP-16.] The APW shell does *not* work. Sometimes there are cosmetic screen display side-effects that are related to other shells. These should not affect the internal operation of the utilities in any way.

--------------------
Disk Sizes and Types
--------------------
Testing has been performed on 720K and 1440K 3.5" disks (and 800K MSDOS disks created using the PC-Transporter), on 360K 5.25" disks attached via an Applied Engineering PC-Transporter, and on 100Mb Zip and 44Mb and 105Mb SyQuest cartridges (with partitioning). Several people are using Floptical drives, mostly attached to RamFast SCSI cards. There is every reason to believe that 1200K 5.25" disks and 1600K and 2880K 3.5" disks should work correctly, but at present they have not been tested. Lastly, PC-Transporter hard disk partitions (in the form of ProDOS files) are supported.

Fixed hard disks will (usually) work, but there may be problems getting them mounted in the Finder. The Finder usually offers to format the disk, and when you decline it marks the disk as 'offline', effectively making it invisible. One workaround to this is to power the drive off then on again after entering a command shell such as ORCA or COMMAND.COM, or by booting directly into such a shell.

In general, the size (capacity) of a disk should not matter with the exception of MFormat, and possibly MDiskCopy which may need to do a low-level format as well. You should be prepared for slower access to larger disks. Many more blocks need to be read/written for the larger FAT and directory areas. Also, scanning the FAT for free blocks takes longer, which is particularly noticeable at the end of a directory listing on a large hard disk. Maybe one day I'll rewrite the code in assembler to speed it up, but it's a low priority as the speed is not an issue on floppy disks.

The utilities can read and write to PC Transporter MSDOS hard-disk partition files on a GS/OS hard disk. See the extra explanation below (after the Device Numbers section) for details of how to use this feature.

--------------------
Windows 95, VFATs and Long File Names
--------------------
Windows 95 (actually, it was Windows NT!) introduced the concept of the VFAT file system and long filenames with a maximum of 255 characters (a 'slight' increase over the original 11 characters!). The MSDOS Utilities will display long filenames where appropriate, and will always correctly handle disks and directories containing long filenames. At present, however, there is no support for long filenames as input parameters to most of the utilities. In particular, this means that you generally cannot create or search for files with long filenames.

***********************  =======
There is one exception!  MRename *does* create long filenames, if appropriate.
***********************  =======

To reduce the risk of problems for people who do not have access to Windows 95 systems or who use the GS/OS MSDOS FST, MRename will not automatically create long filenames unless one or more of the following conditions exist:-

1) The '/L' (for 'L'ong names) flag is specified on the command line
2) The specified new name is too long or contains otherwise illegal characters
3) There is an existing long name for the file

Notes:

- You can enter blanks and other special characters for the new name by enclosing the name in double quotes, eg. "A long file name!.text"

- A short name entry will be automatically generated from the long name. The generated name generally follows MicroSoft's (fairly complicated) rules for shortening long names.

- MCOPY will attempt to use the MSDOS long name when creating the GS/OS file. This is particularly useful when copying to a HFS disk. (You still need to use the short name to specify which file to copy.)

- You can use MDIR to display long filenames to determine the correct short name to use with other utilities. However, keep in mind that if Windows 95 has processed the file since you last looked at it on the IIgs, then the 'generated' short name *may* have changed - even though the long name remains the same!

The important thing to remember is that for compatability with earlier versions of MSDOS, all Windows 95 utilities *must* create short filenames along with the long name. Typically a file named 'Long Name.txt' would have a short name that looked like 'LONGNA~1.TXT'. Also, all utilities must be able to read files using a short name only. What this means is that you still have full compatibility with all of the new Windows 95 applications, even if you create files without long names.

These notes are summarised in the MSDOS.Win95 file in the HELP directory.
                      
Warning: The GS/OS MSDOS FST is confused by disks containing long filenames. It thinks they are volume labels. This is less of a problem if the MSDOS disk is given an explicit volume name before any files with long names are written to it. You can always delete all files and use MLabel to create a volume label.

--------------------
Applied Engineering PC Transporter (AEPCT)
--------------------
To use drives attached to the IIgs through an AE PC Transporter, remember to activate the AEPCT ProDOS drivers using the PCTSWAP program before running any MSDOS commands (otherwise the drives cannot be 'seen' by GS/OS). You should also deactivate them again (or the 5.25" drives at least) before running or returning to desktop applications - otherwise the continuous "polling" of the drives will slow down your system dramatically. Note that this can be done from COMMAND.COM. If you have not already installed the AEPCT ProDOS drivers, you will need to do so using the PCTINSTALL program.

The AEPCT ProDOS drivers were designed for 360K 5.25" drives. They will operate with 720K 3.5" drives attached to the PCT, but only the first 40 tracks (ie. 360K) will be usable. (720K drives work correctly from the MSDOS side of the AEPCT because different drivers are used.) In practice, this means that the root directory is always readable, and as long as the used space does not go over about 320K everything else should work reasonably well also. Two major casualties are MFormat and MDiskCopy which need to be able to "see" the entire disk. However, you *can* perform a 'Quick' format, since that only erases the root directory and FAT tables.

The AEPCT does not support high-density (1200K 5.25" and 1440K 3.5") drives.

See the explanation below (after the Device Numbers section) for details of how to read and write to a PC Transporter MSDOS hard-disk partition file.
       
--------------------
Hard Disk Partitions
--------------------
The utilities are able to handle normal MSDOS hard disk partitions (SCSI partitions are handled outside the control of the utilities). Note that a SCSI hard disk may theoretically have more than one MSDOS 'SCSI-partition', each containing up to 4 'MSDOS-partitions' (the schemes are not mutually exclusive).

If the drive is partitioned, and you don't specify a partition number, the utilities will try use the partition that is marked as 'bootable' in the partition table.

At present, the utilities will handle partitions numbered 1 to 4 per device (there can only be 4 normal partitions per device). The interesting point is the order that they are numbered! I have seen partition tables with the partitions numbered in 1-2-3-4 order, and others in 4-3-2-1 order! Since the utilities must assume one particular order, if you think that a hard disk is partitioned for MSDOS, you should try *all* the partition numbers from /1 to /4 before assuming there is nothing there. The MFDisk utility may prove useful here.

It is possible for a partition to be an 'extended' partition - which basically points to other partitions within itself. The utilities at present will only the read the *first* partition pointed to by an extended partition table entry. However, you should note that this feature has not yet been tested!

--------------------
Device Numbers
--------------------
The utilities all need the MSDOS drive device number as a parameter. If you don't know it already, the Online program may help. Alternatively, simply try the MDIR command with device numbers starting at 2 (since 1 will be the GS/OS boot drive) until you find the right device or until you are told that 'no such device' exists. The ONLINE command will list all online devices and their device numbers, and will also recognise MSDOS drives *containing MSDOS disks*.

Device numbers in GS/OS pathnames are normally specified as '.Dx', (for example, .d3). The '.D' is required to distinguish the device number from a GS/OS prefix number. Since prefixes do not exist in MSDOS, the utilities will all accept a simple number for the device number - no need for the leading '.D'! The one exception is when specifying an MSDOS file or path name beginning with a number (eg. 123.EXE). In this case you *must* specify the device number in '.Dx' form.

In all utilities (except GMCopy), the device number can be specified in one of two ways. Firstly (except for GMCopy), all utilities will accept the device number as the first parameter after the command name. For example:

       MCOPY  .D7  *.TXT  /GSOS.DISK

Secondly, *all* utilities (including GMCopy) will accept the device number as part (or all) of the MSDOS path/file name. For example:

       MCOPY  .D7/*.TXT   /GSOS.DISK
       GMCOPY  /GSOS.DISK  7/FILES  /P                ('.D' not required!)

The reason for the GMCopy exception is that an otherwise legal command such as:

       GMCOPY  .D7  .D6  /P

might mean to copy from GS/OS device 6 to MSDOS device 7 (using the old method), or from GS/OS device 7 to MSDOS device 6 (using the new method)!

--------------------
AE PC Transporter MSDOS Partition Files
--------------------
Device number 0 is a special case. It tells the utilities to read a text file called 'AEPCT.HD.Name' (you must create this file yourself) in the same directory that contains the MSDOS Utilities programs. The first line of this file must contain the pathname of an Applied Engineering PC Transporter MSDOS hard-disk partition file on a GS/OS volume. If the logical MSDOS partition is larger than 16Mb, then the Applied Engineering software will create two physical GS/OS files. In this case, the pathname of the second file must be placed on the second line. Any other lines will be ignored. If you don't own a PC Transporter card, or don't have an MSDOS partition file on your hard disk, then you don't need to worry about this.

An example entry in the file named 'AEPCT.HD.Name' might read :

      /MY.HARD.DISK/AEPCT.Files/MSDOSVOL1

If there are two partition files, the 'AEPCT.HD.Name' file might look like :

      /MY.HARD.DISK/AEPCT.Files/MSDOSVOL1
      /MY.HARD.DISK/AEPCT.Files/MSDOSVOL2

** Warning **: The partition file(s) must not be 'locked', or the utilities will be unable to open the file, even for 'read-only' activities. The disk that the file is on may be write protected, however.

** Note **: MFormat and MDiskCopy do not support MSDOS Partition files.

** Note **: ProSel-16 users will need to set prefix 9 to the location of the 'AEPCT.HD.Name' file, which is normally in the same place as the utilities themselves. This can be done with the command 'PREFIX 9=6'. See the earlier Prosel-16 section.
                  
--------------------
Setting a Default Device Number
--------------------
Beginning with version 2.10 of the MSDOS Utilities, it is possible to set a default MSDOS device number for the utilities. There are two ways this can be done. The first (and fastest) method (setting a shell variable) is for users of the ORCA and GNO/ME command shells. In your login file, or from the command line, enter the following commands to set device 3 as the default MSDOS device for all utilities:

set    MSDOSDevice 3
export MSDOSDevice

The process is similar in GNO/ME, except I'm not sure if the 'export' statement is required - check the manual for details. Many GNO/ME users have reported successfully setting the default device this way.

The second method, which will work for all users with any shell, requires you to create a text file called 'MSDOS.Device' in the same directory that contains the MSDOS utility programs. The first line of this file must contain the device number to be used as the default MSDOS disk device. Any other lines will be ignored.

An example line in the file named 'MSDOS.Device' might read :

.d3
                  
In either case, the utilities will now attempt to use device 3 as the MSDOS disk drive. To override the default, simply specify a device number in the command as though a device number default had not been created.

For example, instead of entering a command as:

     GMCOPY  Prodos.file  .d3/msdos.txt        or       MDIR 3 /w

you only need to enter the command as:

     GMCOPY  Prodos.file  msdos.txt            or       MDIR /w


** Note **: ProSel-16 users will need to set prefix 9 to the location of the 'MSDOS.Device' file, which is normally in the same place as the utilities themselves. This can be done with the command 'PREFIX 9=6'. See the earlier Prosel-16 section.

--------------------
Copying from MSDOS to MSDOS
--------------------
The utilities all assume that only *one* MFM-capable drive exists. Thus you cannot copy from one MSDOS disk to another, except via GS/OS. Note that this should not normally be a problem as most directory information is preserved when copied to GS/OS (the exceptions are attributes such as Read-Only, etc.), and the information can be copied back to the MSDOS disk with the file. (On the other hand, directory information *is* lost when copying to MSDOS. For example, a file copied to MSDOS and back to GS/OS loses its filetype and creation dates.)

MDiskcopy, in particular, is specifically designed to be a single drive copy, as there are alternatives (such as the ORCA/M copy command) which can perform a two-drive copy of an 'unknown' disk type.

***Exception***: Using System 6.01 and Apple's MSDOS FST, it is possible to read MSDOS disks in one drive and write to MSDOS disks in another. This is because the MSDOS FST makes the source disk appear to these utilities as a 'GS/OS' disk.    Note that in this case you should copy files using the '/B' (binary file mode) switch to ensure that extra line feeds are not added unnecessarily. Although attributes such as 'Read-Only' are lost, they may be corrected with MAttrib.

--------------------
Default Translation of File Contents
--------------------
(See the new 'Automatic text file recognition' notes below).
Since it is anticipated that the most common use for the copying utilities will be to copy text files, this is the default copy mode. In this mode, files copied to MSDOS will have a linefeed added after each carriage-return character, and files copied from MSDOS will have linefeed characters after carriage-return characters removed. Also, when copying *from* MSDOS using MCOPY, the file will
be terminated after the first 'control-Z' character (the end-of-file character).

If these translations are not required, use the '/B' (for Binary) parameter. Files copied from MSDOS to GS/OS will be given a filetype of TXT unless the '/B' parameter is used, when they will have a filetype of BIN. If you want '/B' to be the default, you can change it using the MPatch utility.

No other translation of contents is done. For example, an AppleWorks file doesn't become readable by WordPerfect.

--------------------
Automatic text file recognition
--------------------
The '/B' option has the disadvantage that it applies to all files, no matter what the type or contents. You also need to remember whether or not to use it. Using MPatch to make '/B' the default simply reverses the problem.

The solution is automatic recognition of text files. For copying from GS/OS to MSDOS using GMCopy, files of type TXT ($04) or SRC ($B0), with any auxtype or filename, are considered to be text files. For copying from MSDOS to GS/OS using MCopy, files with particular filename extensions are considered to be text files and are saved with type TXT ($04). In both cases, text files will be processed as described above, as though the '/B' option was not specified.

The list of text filetypes recognised during MSDOS to GS/OS copying is based on the list used by the MSDOS FST for a similar purpose. The following extensions are recognised:

.TXT            .ASC            .BAT            .DOC
.DOX            .LST            .ME             .SRC
.ASM            .PAS            .COB            .FOR
.C              .H              .HTM            .RTF
.BSQ

The .DOC extension is a bit of a problem. Once upon a time, and sometimes even today, this type indicated a text "documentation" file used in a similar way to a "READ.ME" file. However, this type more commonly is used to indicate a Microsoft Word word processing file. The bad news is that any attempt to copy an MS Word file will leave the copied file unreadable. The good news is that the file would have been unreadable on a GS anyway! Of course, if you really need to copy such a file (perhaps to take to a Mac or upload to the Net), you can specify the '/A' option to disable 'auto text file recognition' for the copy.

Summary of text/binary command option combinations
--------------------------------------------------
No switch    Automatic text file recognition attempts to translate text files
/A           All files will be treated as text files
/B           All files will be treated as binary (overrides '/A', if specified)

--------------------
File Name Translation
--------------------
Most (short) filenames copied from MSDOS can be used in GS/OS. If a file is copied from MSDOS and no target filename is specified, MCopy will attempt to make the MSDOS filename (using the long filename, if available) suitable for the target file system. For HFS disks, conversion is usually not required! For ProDOS, if the filename contains special characters (such as '$' or '_'), these will be replaced by '.' characters (runs of which will be shortened to single '.' character).  If the resulting name does not begin with an alphabetic character, it will be prefixed by 'A'. (This name conversion is performed by the GS/OS 'JudgeName' system call, if possible.)

Files copied to MSDOS with no target name specified will have any illegal characters (such as from HFS filenames) in the GS/OS filename removed (in particular, including '.' characters). The resulting name is shortened (if necessary) to eight characters plus the first three characters of the name after the last '.' character, by saving the first five and the last three characters. If there is no '.' character, the name will be shortened to the first eight plus last three characters. The aim is to preserve the extension when dealing with a series of filenames like FILE.1, FILE.2, etc.

Examples:

GS/OS filename          MSDOS filename          Notes
--------------          --------------          -----
FRED                    FRED.                   No change
FRED.TXT                FRED.TXT                No change
FRED.TEXT               FRED.TEX                'Extension' was truncated
TOM.DICK.HARRY          TOMDICK.HAR             Extra '.' stripped
LONGFILENAME            LONGFILE.AME            Keep last three characters
LONGFILENAME.1          LONGFAME.1              Compress, keeping 'extension'
FILE FROM HFS           FILEFROM.HFS            Illegal characters stripped

--------------------
General Command Syntax
--------------------
Each command will display its own syntax with examples if entered with a parameter of '?', eg. 'MDIR ?'. Commands that require at least one parameter will display the syntax if the command is entered with no parameters, eg. 'MTYPE'.

Where reasonable, the utilities use an MSDOS-like syntax. For example, using '/x' for command parameters (or 'switches'). To keep the MSDOS-like flavour, whenever the utilities display the device number of the MSDOS drive, they display a drive letter rather than a device number (eg. 'B:' instead of '2').

--------------------
UNIX-style Command Parameters
--------------------
Due to many user requests, beginning with version 2.10, the MSDOS Utilities will accept 'UNIX-style' command switches. For example, the MDIR command to specify a wide display with extra information on device 3 is normally specified as :

MDIR 3 /w /i

It could now be specified as :

MDIR -iw 3      *or*      MDIR -i -w 3      *or*      MDIR -i 3 /w

To use UNIX-style switches, they must be specified as the *first* parameters after the file name (before the device number, if present). They must be preceded by a single '-' rather than a '/' for each parameter, with no separating spaces. You can mix UNIX and MSDOS style switches in the one command.

Note: The MFORMAT command has a volume name switch. Since this is a variable length text parameter, there is no simple way to determine when the parameter ends (without having to use quotes or the like). Therefore it must be the *last* of the UNIX-style parameters in the list. For example,

MFORMAT .d3 /v:my_disk /s:1440

would have to be specified as :

MFORMAT -s:1440v:my_disk .d3

--------------------
Special Characters in File Names (GS/OS and HFS)
--------------------
Files and directories on HFS-formatted GS/OS disks can have spaces and other special characters in their names. Since spaces are normally used as parameter separators, you must use double quotes to surround the parameter. For example, to copy a file named 'FRED' from a HFS directory named 'MSDOS Files' (containing a space in its name) to device 2, you would enter:

     GMCopy  "/HFS/MSDOS Files/FRED"  .D2/FRED.TXT

Note: The quotes are around the entire pathname *parameter*, not just the directory with the space in its name.

Note: If the GS/OS filename you are specifying contains the '/' character, you should use the ':' character as the pathname delimiter. Actually, this is a valid option any time a GS/OS pathname is required.

Note: I am not sure why, but even double quotes may not protect backslash ('\') characters in file names. ORCA/C does *weird* things with parameters containing the '\' character. And for the C programmers among you, simply doubling the '\' is not enough!

--------------------
Auto-Disk Eject
--------------------
Both MFormat and MDiskCopy will automatically eject disks before and during the command operation. For some drives this is silly (for example, 5.25" drives), and for others it can even be a downright nuisance or worse (for example, some floptical or other SCSI drives). Both comands have a '/X' option to suppress auto-eject of disks. If you want '/X' to be the default, you can change it with the MPatch utility.
                                        
--------------------
Disk Interleave
--------------------
If access to 3.5" MSDOS disks seems unreasonably slow, it may be that they were pre-formatted using a 1:1 interleave. You should reformat the disks using a 2:1 interleave (eg. using MFormat's or MDiskCopy's '/I:2' option). It may even be necessary to use a larger interleave value.

--------------------
Compressed Disks Not Supported
--------------------
This note will be obvious to some people, but it is worth mentioning anyway. Software exists in the MSDOS world to increase the space available on disks by compressing the data at the block level on disk. For example, 'Stacker', and MSDOS v6 and later. The former can even create "Stacked" floppy disks. These are *not* usable by the utilities as the data within blocks is not understandable.


Known Problems
==============
Apple's 3.5" Disk Controller seems to have a problem when it does a low-level format on a double-density MFM disk (ie. 720K). The format actually completes, and the system doesn't crash, but you can no longer access *any* 3.5" disks! You must eject the disk and do a 'three-finger-salute' reboot (a normal shutdown does not seem to be enough), after which you can finish the original operation. For example, MDiskcopy will format the target disk if it is unformatted or the wrong size (eg. 800K). After the format, the program fails as described above, but after rebooting the copy proceeds as the disk is now formatted. MFormat similarly fails after the low-level format, but after rebooting you can use the '/Q'uick format option to write the empty directory, etc.

The problem does not occur with 1.4Mb (high-density) disks - this is not really surprising as they are already MFM-formatted for both Apple and MSDOS use. Note that MDiskcopy will copy 720K disks just fine if the target disk has previously been formatted for 720K.

In COMMAND.COM, due a conflict between the text tools and the GS/OS console driver, text screen displays from programs not compiled by a recent ORCA compiler sometimes get 'confused'. Repeating the command is usually enough to resolve the problem.

Other screen-oriented quirks can be seen with early versions (1.x) of GNO/ME, and with the ProSel-16 command shell. Note that these are cosmetic effects only - the MSDOS Utilities themselves otherwise function correctly.

GS/OS volume names consisting of a single character are sometimes confused with program parameters. For example, the command 'MCOPY 2 FILE*.* /P' could mean the user wanted prompting for each file, or he simply wanted to copy all files to a disk named /P. If this is a problem, specify GS/OS path names using the more modern separator of ':' instead of '/'.

The Future
==========
The utilities that are both useful and reasonable have been completed. Since earliest releases I have hoped to write simple UNDELETE and CHKDISK programs, but I think the time has passed. The interleave and size parameter defaults for MFormat may be patchable one day.

This section also used to talk about my plans for a GUI version. However, they are no longer just "plans". Kansasfest 1997 saw the release of MUG! (MSDOS Utilities Graphical !nterface), an NDA version of these utilities.

Because of MUG!, the reality is that that this will probably be the last release of the MSDOS Utilities. Future updates will be made to MUG! (for example, at the time of writing MUG! had support for formatting Zip disks), and only in exceptional circumstances will changes be ported back to the MSDOS Utilities. For those users (like me!) who still like and use shell utilities, I can only say sorry!

The Past   (Summary only - see the Rev.Notes file for further details)
========
v1.00      The first version of this disk did not actually have a version
           number. It only contained three files, early versions of MDIR,
           MTYPE and MCOPY. Nevertheless, it travelled around the world,
           and the people that sent me money for it are solely responsible
           for the disk you see today.

v2.00      This version was a complete rewrite, with many new utilities, and
           in particular, the ability to WRITE to MSDOS disks. The utilities
           still require a command shell to be used, but a simple command
           shell is now included.

v2.10      Many updates to most utilities, especially GMCopy and MFormat.
           Added several extra commands to COMMAND.COM.
           Added MMD, MRD and MFDISK utilities.
           Added MPatch utility to allow some utility defaults to be changed.
!!!        Utilities can now have a default MSDOS device specified, and can
           use UNIX-style parameters. (And I said "never"!)

v2.20      Support for PC Transporter partitions > 16Mb.
           Fixed support for hard disks > 32Mb, and DOS 'Extended' partitions.
           MFormat uses GS/OS format dialogue, and supports 1600K/2880K disks.
           Added MDebug utility to assist me to support new/strange disks.
           Added the PATH command to COMMAND.COM for default command path.
           ShowChain program merged into MDir to save space.

v2.21      Better support for large disks (where FAT size > 64K).
           MMD was incorrectly giving a filesize to subdirectory file entries.
           MDebug now adds a carriage return at the end of each line.
           MMD and MRD have their version resource set correctly.

v2.22      Writing to second PCT Transporter volume file did not work properly.
           MFormat supports the BlueDisk (beta) driver that formats to 1722K.
           Changed my email address.

v2.30      Minimal support for directories with Windows 95 long file names.
           MRename can *create* Windows 95 long file names.
           MFormat and MLabel handle blanks in label names.
           MFormat may be able to create Atari format disks (untested!).
           MRD merged into MDel to save space and handle multiple directories.
           Added hex dump and file verify options to MType.
           Added COPY, LOCK and UNLOCK commands and other stuff to COMMAND.COM.
           Better handling of hard disk partitions (particularly Zip disks)

v2.30a     MRename was creating long file names for valid short file names with
           extensions.

v2.40      GMCopy caused directory/FAT errors after copy errors, eg. disk full.
           MCopy uses Win95 long filenames when creating GS/OS filenames.
           MCopy and GMCopy automatically recognise text files.
           MDiskCopy corrupted the target disk when doing multi-pass copies.
           MDIR said 'No files found' even if it found one or more directories.
           MDIR always displays 'long' filenames (uses short name if necessary).
           MDIR faster with Zip disks by skipping freespace calculation.
           MMD handles disk full errors a little more reliably.
           MType expands tabs to 2 blanks instead of totally ignoring them.
           MPatch and MMD now included as part of the unregistered version.
           findMFM program removed to save space (Online covers the loss).
           Some utilities in a self-extracting ShrinkIt archive to save space.

v2.40a     MCopy had a typo in the usage message.
           Updated the email addresses yet again.


Disk Contents
=============
Read.Me.First      You're reading it!
Disk.Ver.2.40a     An empty file naming the disk version
Credits            Thank these people that the MSDOS Utilities were completed!
Rev.Notes          Revision notes for various programs.
Icons (folder)     Finder icons for the /MSDOS.Tools disk and COMMAND.COM
Help  (folder)     A one screen help file for each program listed below, as
                   well as two overview files named 'MSDOS' and 'MSDOS.PARMS'.
COMMAND.COM        A simple command shell
MDir               Displays directory listings
MType              Types (displays) the contents of files
MCopy              Copies files from MSDOS to GS/OS
GMCopy             Copies files from GS/OS to MSDOS
MRename            Rename files or directories
MDel               Delete files or directories
MLabel             Displays/adds/changes/removes a disk volume label
MAttrib            Displays/changes file attributes
MMD                Creates directories
MFDisk          ** Fixed Disk partition information display
MFormat            Formats floppy disks (including floptical disks)
MDiskCopy          Copies disks with a single drive (not limited to MSDOS)
MPatch             Patches some MSDOS Utility default options
MDebug          ** Dumps disk data to a text file to assist problem resolution
Online             Displays all online devices and their device numbers
Syscmnd.Sample     A sample addition to SYSCMND for ORCA/M users
Extras.SEA      ** ShrinkIt GS archive containing MFDisk and MDebug.

Since the size of the MSDOS Utilities programs and support files has grown to be larger than a single 800K disk, some of the utilities have been compressed using ShrinkIt GS to save space. To extract these utilities onto another disk, simply execute the file Extras.SEA. You will be prompted for a location for the extracted files (make sure you choose a different disk!), then the files will be automatically extracted.

===================================================================

Notice:  These files are SHAREWARE.  That means you may copy them
======   but you may not sell them. Bona-fide User Groups may charge
         their usual copying fee only - up to $7.00. The files may
         be included on shareware compilation disks as long as the
         fee does not exceed $7.00. (Exception: a shareware compilation
         CD-ROM disk may charge more - please contact me for details)

         Joachim Lange of ///SHH Systeme has a license to distribute
         version 2 of the MSDOS Utilities with the BlueDisk interface.

===================================================================

Legal Stuff
===========
    The author of this software makes no warranty or representation
    either express or implied regarding the merchantability or fitness
    of any of the contents of this disk for any particular purpose.
    This software is provided "as is" and the user is assuming the
    entire risk as to its quality and performance.

    The author of this software will not be liable for direct, indirect,
    special, incidental or consequential damages resulting from any defect
    in the software or its documentation.

    ProDOS, GS/OS and Apple are registered trademarks of Apple Computer, Inc.
    Applesoft and Apple IIgs are trademarks of Apple Computer, Inc.
    ORCA/M and ORCA/C are trademarks of The Byte Works, Inc.
    MSDOS and Windows are probably registered trademarks of MicroSoft Inc,
    just as PC Transporter is probably a registered trademark of Applied
    Engineering, and GNO/ME a trademark of Procyon, Inc.

===================================================================

Most programs are written in ORCA/C v2.10. This is the formal acknowledgement:

      These programs contain material from the ORCA/C
      Run-Time Libraries, copyright 1987-1994
      by Byte Works, Inc. Used with permission.

===================================================================
      Peter Watson
      13 Ilios Close
      Forest Hill  Vic  3131
      Australia

      paw@acslink.net.au
      paw77@hotmail.com
===================================================================
